/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.black.cat.utils;

import java.util.Comparator;
import java.util.Map;


public interface PathMatcher {

	/**
	 * 判断指定的路径 path 是否是一个 pattern(模式)
	 * 如果返回值是 false，也就是说 path 不是一个模式，而是一个静态路径(真正的路径字符串),
	 * 那么就不用调用方法 #match 了，因为对于静态路径的匹配，直接使用字符串等号比较就足够了。
	 * @param path
	 * @return
	 */
	boolean isPattern(String path);

	/**
	 * 根据当前 PathMatcher 的匹配策略，检查指定的径 path 和指定的模式 pattern 是否匹配
 	 * @param pattern
	 * @param path
	 * @return
	 */
	boolean match(String pattern, String path);

	/**
	 * 根据当前 PathMatcher 的匹配策略，检查指定的径 path 和指定的模式 pattern 是否之间
	 * 是否为前缀匹配
	 * @param pattern
	 * @param path
	 * @return
	 */
	boolean matchStart(String pattern, String path);

	/**
	 * 给定一个模式 pattern 和一个全路径 path，判断路径中和模式匹配的部分。
	 *
	 *  该方法用于发现路径中的哪一部分是和模式能动态匹配上的部分。它会去除路径中开头静态部分，
	 * 	仅仅返回那部分真正和模式匹配的上的部分。
	 * 	例子 : "myroot/*.html" 为 pattern , "myroot/myfile.html" 为路径，
	 * 	则该方法返回 "myfile.html".
	 * 	具体的检测规则根据当前 PathMatcher 的匹配策略来顶。
	 * @param pattern
	 * @param path
	 * @return
	 */
	String extractPathWithinPattern(String pattern, String path);

	/**
	 * 给定一个模式和一个路径，提取其中的 URI 模板变量信息。URI模板变量表达式格式为 "{variable}"
	 *
	 * 例子 : pattern  为 "/hotels/{hotel}" ，路径为 "/hotels/1", 则该方法会返回一个 map ，
	 * 内容为 : "hotel"->"1".
	 * @param pattern
	 * @param path
	 * @return
	 */
	Map<String, String> extractUriTemplateVariables(String pattern, String path);

	/**
	 * 比较器
	 * @param path
	 * @return
	 */
	Comparator<String> getPatternComparator(String path);

	/**
	 *  合并两个模式。具体合并的算法由实现类决定。
	 * @param pattern1
	 * @param pattern2
	 * @return
	 */
	String combine(String pattern1, String pattern2);

}
